home *** CD-ROM | disk | FTP | other *** search
/ Risc World 3 / Risc World 3.iso / SOFTWARE / ISSUE4 / ZAP / !Zap / Modules / !ZapBasAsm / !Help next >
Text File  |  2002-05-08  |  8KB  |  237 lines
  1. ZapBasAsm help file       for ZapBasAsm v.2.06
  2. © Carl Hetherington 1997
  3. ------------------------
  4.  
  5. ZapBasAsm is an extension module for the Freeware text editor 'Zap'.  It
  6. is intended for programmers who write assembler code for the built-in BASIC.
  7.  
  8. Its main feature is that it provides syntax-colouring of assembler within
  9. BASIC programs.  Based on Zap's own BASTXT mode, it detokenises normal BASIC
  10. files on loading and then colours the whole file as if it were assembly. 
  11. Whereas this can give some rather strange colours to any actual BASIC within
  12. these files, it gives all mnemonics, registers, constants etc. different
  13. colours.  This can have a surprisingly beneficial effect on source-code
  14. readability.
  15.  
  16. In addition to this the module provides a few handy Zap commands which can be
  17. bound to certain keypresses and in certain cases called from Zap menus.  In
  18. the current version these are:
  19.  
  20. BASM_LABELLIST        gives a list of labels defined within a file
  21. BASM_MULTIPLE        checks for multiple definitions of labels
  22. BASM_NUMBERLABEL    automatically numbers labels consecutively
  23. BASM_INSERTPREFIX    completes label names
  24.  
  25. More details of these commands are given later in this file.
  26.  
  27.  
  28.  
  29. Installation
  30. ------------
  31.  
  32. To install !ZapBasAsm, you will need to do the following:
  33.  
  34. 1.    Open the !Zap directory by holding down shift and double-clicking on
  35. the !Zap icon in its filer window.
  36.  
  37. 2.    Open the Modules directory within !Zap.
  38.  
  39. 3.    Copy !ZapBasAsm into this directory.
  40.  
  41. 4.    Quit !Zap if its already loaded, and reload it.
  42.  
  43. Once this is done there is only one further consideration to make.  For the
  44. mode to work properly any BASIC files that you want to edit with BasAsm must
  45. be loaded in by either the BASTXT or BasAsm modes.  You do not need to worry
  46. about this unless you have Zap set up to use the BASIC mode by default for
  47. BASIC files.  If you do have this setup, you will need to do one of the
  48. following:
  49.  
  50. 1.  Set up Zap to load BASTXT or BasAsm for all BASIC files. If you load into
  51. BASTXT you can simply select BasAsm from the Mode menu after the file has
  52. loaded.
  53.  
  54. 2.  Set up Zap to load BasAsm for all your BASIC files that contain assembly. 
  55. This is the best solution but as you can guess, the problem is telling Zap
  56. how to recognise BASIC assembler files.  One way is to put all your assembler
  57. files into a directory called, for example, 's' and then to alter Zap's
  58. configuration to load these particular files into BasAsm.
  59.  
  60. If you don't get this bit right you will find that when selecting BasAsm the
  61. file will turn into a complete mess!
  62.  
  63.  
  64.  
  65. Syntax colouring
  66. ----------------
  67.  
  68. Once you have installed ZapBasAsm it will colour assembler sections
  69. automatically whenever it is selected.  You may want the BasAsm mode to be
  70. selected by default for some or all BASIC files; this is discussed later. 
  71. Otherwise you will need to load BASIC files into the BASTXT mode and then
  72. select ZapBasAsm from the Mode.Load mode menu.
  73.  
  74. The colours BasAsm mode uses may be configured. If you are unsure of how to 
  75. do this, read the !Help file that comes with Zap.
  76.  
  77.  
  78. Commands provided by ZapBasAsm
  79. ------------------------------
  80.  
  81. As mentioned above, ZapBasAsm provides four new Zap commands.
  82.  
  83.  
  84. BASM_LABELLIST
  85.  
  86. This is the simplest of the three.  When called it simply calls the Zap
  87. search code with a search string that (hopefully) finds just label
  88. definitions.  These are sent to a throwback window for your perusal.
  89. This option can be selected from the Mode->BasAsm menu.
  90.  
  91.  
  92. BASM_MULTIPLE
  93.  
  94. This command is designed to find labels that have been defined more than once
  95. within a particular file.  Multiple definitions can give rise to all manner
  96. of strange errors and its worth calling this function if you have a strange
  97. bug that you can't fix.  If any multiple definitions are found they are
  98. listed in a throwback window; if labels are defined more than twice they
  99. appear more than once in the throwback window.  Note that in this version you
  100. can't click on labels in the throwback window to move to them; you'll have to
  101. use the standard search function once the multiple labels have been found.
  102. This option can also be selected from the Mode->BasAsm menu.
  103. Note that if you have labels longer than 256 characters in length then
  104. strange things may happen.
  105.  
  106.  
  107. BASM_NUMBERLABEL
  108.  
  109. This is a command which may or may not suit your way of working.  Because of
  110. the fact that you can't have duplicate labels in the BASIC assembler, I tend
  111. to give common labels, for example loop and skip, consecutive numbers to
  112. differentiate them.  For example there might be a sequence of code
  113.  
  114. .routine_loop1
  115. <code>
  116. BNE routine_skip1
  117. <code>
  118. .routine_skip1
  119. BLT routine_loop1
  120. .routine_loop2
  121. ...etc
  122.  
  123. The only problem with this is knowing which numbers have been used and which
  124. have not.  This is where this command comes in.  It is used when you have
  125. typed the start of a new label, e.g.
  126.  
  127. .routine_loop
  128.  
  129. If you then call BASM_NUMBERLABEL, Zap will look through the file for any
  130. other labels of the form routine_loopx, where x is a number, and will then
  131. enter the next number up in the sequence.
  132.  
  133. This sounds rather complicated, but works quite well in practice.  With the
  134. above example of code, I could then type
  135.  
  136. .routine_skip
  137.  
  138. and then call BASM_NUMBERLABEL and a 2 would be entered.
  139. Note that using numbers of more than 3 digits with this command may cause
  140. unpredictable behaviour.
  141.  
  142.  
  143. BASM_INSERTPREFIX
  144.  
  145. This is another command that may or may not help you, depending on the style
  146. of source code that you write.  Because of the way I avoid duplicate labels,
  147. the label names can end up being rather long and tedious to type.  The
  148. BASM_INSERTPREFIX command, when bound to a handy key, can help.  Basically it
  149. tries to decide what the current subroutine that you are in is called, and
  150. inserts this name at the cursor.  This can be useful in situations like:
  151.  
  152. .a_long_routine_name
  153.  
  154. . [*] a_long_routine_name_loop1
  155. MOV r0,r0
  156. B [*] a_long_routine_name_loop1
  157.  
  158. Executing BASM_INSERTPREFIX at the places marked by [*] inserts
  159. 'a_long_routine_name'.  The best way to understand it is to try it out; if it
  160. doesn't work for you then just forget about it.
  161.  
  162.  
  163.  
  164.  
  165.  
  166. Notes
  167. -----
  168.  
  169. ZapBasAsm is based on Zap's original BASTXT mode so you will need the
  170. ZapBASIC module available for it to work.  This module is supplied with all
  171. recent versions of Zap.
  172.  
  173. I can accept no liability for any loss of data that this module causes.
  174.  
  175.  
  176.  
  177.  
  178.  
  179. Credits and thanks
  180. ------------------
  181.  
  182. This module would not have been possible without the helpful inhabitants of
  183. csa.programmer who responded to all my various requests for help.  In
  184. particular I would like to thank:
  185.     Tim Tyler    for helpful emails
  186.     Guttorm Vik    for some source code and ideas
  187.     Matthew Wilcox    for the source to his BasCat program
  188.     Darren Salt    for good ideas
  189.     Matthew Hambley    for releasing the source code to his ZapHTML
  190.             module for me to, ahem, read ;-)
  191.     Dominic Plunkett  for coding tips
  192.     Chris Claydon    for bug reports
  193.     Neil Walker    for more bug reports
  194.     Dickon Hood    for encouragement, bug reports and suggestions
  195.             
  196.             
  197. I'm sorry if I've forgotten anyone.  Of course we must thank Dominic Symes
  198. and the other Zap developers for writing Zap in the first place!
  199.  
  200.  
  201.  
  202.  
  203.  
  204. Copyright
  205. ---------
  206.  
  207. The conditions of copying this program and its accompanying files are the
  208. same as those of the main Zap application.
  209.  
  210. This software is supplied as is with no warranty express or implied about its
  211. suitability for any particular purpose.
  212.  
  213. The ZapBasAsm module and all accompanying files are © Carl Hetherington 1997.
  214.  
  215.  
  216.  
  217. Getting in touch
  218. ----------------
  219.  
  220.   Bug reports should be sent to 
  221.  
  222.         bugs@zap.tartarus.org
  223.  
  224.   Feature requests should be directed towards
  225.  
  226.         zap-features@zap.tartarus.org
  227.  
  228.  
  229. There are a also a number of mailing lists you can subscribe to - see
  230. Zap's web pages for details:
  231.  
  232.         http://zap.tartarus.org/
  233.  
  234.  
  235. I hope you find ZapBasAsm useful.
  236. Carl Hetherington.
  237.